Microsoft CodeView and Utilities
================================
PART 1 <> THE CODE VIEW DEBUGGER

Part 1 explains the use of the CodeView debugger.  Commands, display, and
interface of the debugger are presented here, while other material relevant to
the debugger (such as error messages and exit codes) is presented in the
Appendices.

Chapter 1 explains how to create a C, FORTRAN, BASIC, Pascal or assembly
program that can be run with the CodeView debugger; it also explains how to
start the debugger and select various command line options.

Chapter 2 discusses the CodeView display sccreen and interface, including
function keys, keyboard commands, and the mouse.

Chapters 3-11 of Part 1 describe how to use each of the CodeView commands and
expressions.

CHAPTER 1 ___ GETTING STARTED

Getting started with the CodeView debugger requires several simple steps.
First you must prepare a special-format executable file for the program you
wish to debug; then you can invoke the debugger.  You may also wish to specify
options that will affect the debugger's operation.

This chapter describes how to produce executable files in the CodeView format
using C, FORTRAN, BASIC, Pascal, or assembly language, and how to load a pro-
gram into the CodeView debugger. The chapter lists restrictions and program-
ming considerations with regard to the debugger, which you may want to consult
before compiling or assembling. Finally, the chapter describes how to use the
debugger with Microsoft of IBM Macro Assembler, Versions 1.0 through 4.0.

1.1  Restrictions

This list briefly describes kinds of files that are not directly supported by
the debugger.  The following restrictions apply generally to the use of the
CodeView debugger, regardless of the language being used.

Restriction			Explanation
-----------------------------------
Include files		You will not be able to use the CodeView debugger to
			debug source code in include files.

Packed files		CodeView symbolic information cannot be put into a
			packed file.

.COM files		Files with the extension .COM can be debugged in
			assembly mode only; they can never contain symbolic
					information.

Memory-resident		The CodeView debugger can only work with disk-resident
programs		.EXE and .COM files.  Debugging of memory-resident
			files is not supported.
Programs that		Programs run under CodeView debugger can read the DOS
alter the		environment, but they cannot permanently change it.
environment		Upon exit from CodeView, all changes to the environ-
			ment are lost.

Program Segment		The CodeView debugger automatically preprocesses a
Prefix (PSP)		program's PSP the same way a C program does; quote
			marks are removed, and exactly one space is left be-
			tween command-line arguments.  This preprocessing only
			creates a problem if you are debugging a program not
			written in C - one that tries to access command-line
			arguments.

Some of the features that are now allowed by CodeView include debugging of
library modules and debugging of overlayed code.  CodeView users can now
freely debug library modules and overlays.

1.2  Preparing Programs for the CodeView Debugger

You must compile and link with the correct options in order to use a program
with the CodeView debugger.  These options direct the compiler and the linker
to produce an executable file, which contains line-number information and a
symbol table, in addition to the executable code.
-----
Note
----
For the sake of brevity, this section and its three subsections use the term
"compiling" to refer to the process of producing object modules.  However,
almost everything said about compiling in this section applies equally well
to assembling.  Exceptions are noted in Section 1.2.8, "Preparing Assembly 
Programs."
====
Not all compiler and linker versions support CodeView options. (Consult the
section on the appropriate language below for information about compiler ver-
sions.  Also, you will need to use the Micrsoft Overlay Linker, Version 3.6
or later.)  If you try to debug an executable file that was not compiled and
linked with CodeView options, or if you use a compiler that does not support
these options, then you will only be able to use the  debugger in assembly
mode.  This means that the CodeView debugger will not be able to display
source code or understand source-level symbols, such as symbols for functions
and variables.

1.2.1  Programming Considerations

Any source code that is legal in C, FORTRAN, BASIC, Pascal or Microsoft Macro
Assembler can be compiled or assembled to create an executable file and then
debugged with the CodeView debugger.  However, some programming practices make
debugging more difficult.

Each of the Microsoft languages listed above permits you to put code in
separate include files and to read the files into your source file by using an
include directive.  However, you will not be able to use the CodeView debugger
to debug source code in include files.  The preferred method of developing
programs is to create separate object modules and then link the object modules with your program.  The CodeView debugger supports the debugging of separate
object modules in the same session.

Also, the CodeView debugger will be more effective and easier to use if you
put each source statement on a separate line.  A number of languages (C and
BASIC in particular) permit you to place more than one statement on a single
line of the source file.  This practice does not prevent the CodeView debugger
from functioning.  However, the debugger must treat the line as a single unit;
it cannot break the line down into separate statements.  Therefore, if you
have three statements on the same line, you will not be able to put a break-
point or freeze execution on the individual statements.  The best you will be
able to do is freeze execution at the beginning of the three statements, or at
the beginning of the next line.

Some languages (C and assembly in particular) support a type of macro
expansion.  However, the CodeView debugger will not help you debug macros in
source mode.  You will need to expand the macros yourself before debugging
them, otherwise the debugger will treat them as simple statements or instruc-
tions.

Finally, your segments should be declared according to the standard Microsoft
format (as described in the Mixed-Language Programming Guide).  This is taken
care of for you automatically with each of the Microsoft high-level languages.

1.2.2  CodeView Compile Options

----
Note
----
Microsoft compilers will accept command-line options that are preceded by
either a forward slash (/) or a dash (-).  For brevity, this manual will
list only the forward slash when describing options, but you may use either
symbol.

The use of uppercase or lowercase letters is significant for options used
with the C, FORTRAN, BASIC and Pascal compilers; you must type the letters
exactly as given.
====

When you compile a source file for a program you want to debug, you must
specify the /Zi option on the command line.  The /Zi option instructs the
compiler to include line-number and symbolic information in the object file.
If you do not need complete symbolic information in some modules, you can
compile those modules with the /Zd option instead of /Zi.  The /Zd option
writes less symbolic information to the object file, so using this option
will save disk space and memory.  For example, if you are working on a program
made up of five modules but only need to debug one module, you can compile
that module with the /Zi option and the other modules with the /Zd option.
You will be able to examine global variables and see source lines in modules
compiled with the /Zd option, but local variables will be unavailable.

----
Note:  The /Zd option is not available with QuickBASIC.
====

In addition, if you are working with a high-level language, you will probably
want to use the /Od option, which turns off optimization.  Optimized code
may be rearranged for greater efficiency and, as a result, the instructions
in your program may not correspond closely to the source lines.  After debugg-
ing, you can compile a final version of the program with the optimization level
you prefer.

----
Note:  The /Od option is not available with QuickBASIC or the Macro Assembler.
====

You cannot debug a program until you compile it successfully.  The CodeView
debugger will not help you correct syntax or compiler errors.  Once you
successfully compile your program, you can then use the debugger to locate
logical errors in the program.

Compiling examples are given in the sections below on compiling and linking
with specific languages.

1.2.3  CodeView Link Options

If you use LINK separately to link an object file or files for debugging, you
should specify the /CODEVIEW option (it can be abbreviated as  /CO).  This
instructs the linker to incorporate addresses for symbols and source lines
into the executable file.

Note that if you use a Microsoft driver program that automatically invokes the
linker (such as CL with C, or FL with FORTRAN), then the linker will auto-
matically be invoked with the /CO option whenever you specify /Zi on the 
command line.  You do not use /CO unless you are invoking the linker directly
by typing LINK.

Although executable files prepared with the /CODEVIEW option can be executed
from the DOS command line like any other executable files, they are larger
because of the extra symbolic information in them.  To minimize program size,
you will probably want to recompile and link your final version without the
/Zi option when you finish debugging a program.

Linking examples are given in the sections below on compiling and linking
with specific languages.

1.2.4  Preparing C Programs

In order to use the CodeView debugger with a program written in C, you need
to compile it with the Microsoft C Compiler, Version 4.0 or later.  Earlier
versions of the compiler do not support the CodeView compile options.  You
also need to link with the Microsoft Overlay Linker, Version 3.6 or later.

Writing C Source Code

Microsoft C supports the use of include files through the use of the #include
directive.  However, you will not be able to debug source code  put into
include files.  Therefore, you should reserve the use of include files for
#define macros and structure definitions.

The C language permits you to put more than one statement on a line.  This
practice makes it difficult for you to debug such lines of code.  For example,
the following code is legal in C:

code = buffer[count]; if (code == '\n') ++lines;
This code is made up of three separate source statements.  When placed on the
same line, the individual statements cannot be accessed during debugging.  You
could not, for example, stop program execution at ++lines;.  The same code
would be easier to debug in the following form:

code = buffer[count];
if (code == '\n')
		   ++lines;

This makes code easier to read and corresponds with what is generally
considered good programming practice.

You cannot easily debug macros with the CodeView debugger.  The debugger will
not break down the macro for you.  Therefore, if you have complex macros with
potential side effects, you may need to write them first as regular source
statements.

Compiling and Linking C Programs

The /Zi, /Zd, and /Od options are all supported by the Microsoft C Compilers,
Versions 4.0 and later.  (For a description of these options, see Section
1.2.2, "CodeView Compile Options.")  The options  are accepted by the CL
driver and the MSC drjiver, which was supplied with Version 4.0.  Linking
separately with /CO is necessary when you compile with MSC.

The CodeView debugger supports mixed-language programming.  For an example of
how to link a C module with modules from other languages, see Section 1.2.8,
"Preparing Assembly Programs."

<*> Examples

CL /Zi /Od EXAMPLE.C

MSC /Zi /Od EXAMPLE
LINK /CO EXAMPLE;

CL /Zi /Od /c MOD1.C
CL /Zd /Od /c MOD2.C
CL /Zi MOD1 MOD2

In the first example, CL is used to compile and link the source file
EXAMPLE.C.  CL creates an object file in the CodeView format, EXAMPLE.OBJ, and
then automatically invokes the linker with the /CO option.  The second example
demonstrates how to compile and link the source file EXAMPLE.C by using the
MSC program provided with Version 4.0 of the compiler.  Since MSC does not
invoke the linker, you must invoke the linker directly, and specify /CO on the
command line.  Both examples result in an executable file, EXAMPLE.EXE, which
has the line-number information, symbol table, and unoptimized code required
by the CodeView debugger.

In the third example, the source module MOD1.C is compiled to produce an
object file with full symbolic and line information, while MOD2.C is compiled
to produce an object file with limited information.  Then, CL is used again to link the resulting object files.  (This time, CL does not recompile because
the arguments have no .C extension.)  Typing /Zi on the command line causes
the linker to be invoked with the /CO option.  The result is an executable
file in which one of the modules, MOD2.C, will be harder to debug.  However,
the executable file will take up substantially less space on disk than it
would if both modules were compiled with full symbolic information.

1.2.5  Preparing FORTRAN Programs

In order to use the CodeView debugger with a program written in FORTRAN, you
will need to compile it with the Microsoft FORTRAN Optimizing Compiler,
Version 4.0 or later.  Earlier versions of the compiler do not support the
CodeView compile options.  You will also need to link with the Microsoft
Overlay Linker, Version 3.6 or later.

Writing FORTRAN Source Code

The Microsoft FORTRAN compiler supports the use of include files through use
of the $INCLUDE directive.  However, you will not be able to debug source code
in an include file.  If you have source code that you wish to put in separate
files, then you should use the techniques of separately compiled modules.  The
CodeView debugger does support this technique by allowing you to trace through
separate source files in the same session.

Compiling and Linking FORTRAN Programs

The /Zi, /Zd, and /Od options are all supported by the Microsoft FORTRAN
Optimizing Compiler, Version 4.0.  For a description of these options, see
Section 1.2.2, "CodeView Compile Options."  The CodeView debugger supports
mixed-language programming.  For an example of how to link a FORTRAN module
with modules from other languages, see Section 1.2.8, "Preparing Assembly
Programs."

<*>  Examples

FL /Zi /Od EXAMPLE.FOR

FL /Zi /Od /c EXAMPLE.FOR
LINK /CO EXAMPLE;

FL /Zi /Od /c MOD1.FOR
FL /Zd /Od /c MOD2.FOR
FL /Zi MOD1 MOD2

In the first example, FL is used to compile and link the source file
EXAMPLE.FOR.  FL creates an object file in the CodeView format, EXAMPLE.OBJ,
and then automatically invokes the linker with the /CO option.  The second
example demonstrates how to compile and link the source file EXAMPLE.FOR by
using separate steps for compiling and linking.  In this case, the /CO option
must be given explicitly to the linker.  Both examples result in an executable
file, EXAMPLE.EXE, which has the line-number information, symbol table, and
unoptimized code required by the CodeView debugger.

In the third example, the source module MOD1.FOR is compiled to produce an object file with full symbolic and line information, while MOD2.FOR is
compiled to produce an object file with limited information.  Then FL is used
again to link the object files. (Note that this time, FL does not recompile,
because the arguments have no .FOR extension.)  Typing /Zi on the command line
causes the linker to be invoked with the /CO option.  The result is an
executable file in which one of the modules, MOD2.FOR, will be harder to
debug.  However, the executable file takes up substantially less space on disk
than it would if both modules were compiled with full symbolic information.

1.2.6  Preparing BASIC Programs

In order to use the CodeView debugger with a program written in BASIC, you
will need to compile it with Microsoft QuickBASIC, Version 4.0 or later.  You
will also need to link with the Microsoft Overlay Linker, Version 3.6 or
later.

Writing BASIC Source Code

Microsoft BASIC supports the use of include files through the use of the REM
$INCLUDE directive.  However, you will not be able to debug source code put
into include files.  The preferred practice for developing source code in
separate files is to use separately compiled modules.  The CodeView debugger
does not support this technique by allowing you to trace through separate
source files in the same session.

BASIC also permits you to put more than one statement on a line.  This
practice makes it difficult for you to debug such lines of code.  For example,
the following code is legal, even common, in BASIC:

SUM=0 : FOR I=1 TO N : SUM=SUM+ARRAY(I) : NEXT I

This code is actually made up of four separate BASIC statements.  When placed
on the same line, the individual statements cannot be accessed during
debugging.  You could not, for example, stop program execution at
SUM=SUM+ARRAY(I).  The same code would be easier to debug if it were written
in the following form:

SUM=0
FOR I=1 TO N
	SUM=SUM+ARRAY(I)
NEXT I

Compiling and Linking BASIC Programs

Versions 4.0 and later of QuickBASIC can prepare BASIC programs for use with
the CodeView debugger, through the use of the BC command line.  You cannot
prepare programs for use with CodeView when you are in the QuickBASIC editor
itself.  Instead, compile separately with the BC command-line option /Zi.  The
/Zi option is described in Section 1.2.2, "CodeView Compile Options."  You
must also link separately with /CO.

The CodeView debugger supports mixed-language programming.  For an example of
how to link a BASIC module with modules from other languages, see Section
1.2.8, "Preparing Assembly Programs."

<*>  Example

BC /Zi EXAMPLE;
LINK /CO EXAMPLE;

The example above compiles the source file EXAMPLE.BAS to produce an object
file, EXAMPLE.OBJ, which contains the symbol and line-number information
required by the CodeView debugger.  Then the linker is invoked with the /CO
option to create an executable file that can be used with the debugger.

1.2.7  Preparing Pascal Programs

In order to use the CodeView debugger with a program written in Pascal, you
will need to compile it with the Microsoft Pascal Compiler, Version 4.0 or
later.  Earlier versions of Pascal do not support the CodeView compile
options.  You will also need to link with the Microsoft Overlay Linker,
Version 3.6 or later.

----
Note
----
If you have a version of Microsoft Pascal earlier than Version 4.0, you can
use the CodeView debugger to a limited extent.  However, the debugger will
not be able to evaluate program symbols in CodeView commands.  Compile a
program as you would normally and then link with the /CO option as explained
below.  You will then be able to use CodeView to step through your program 
and set breakpoints.  The debugger will also be able to display machine-
level code and do memory dumps.
====

Writing Pascal Source Code

Microsoft Pascal supports the use of include files by providing the $include
metacommand.  However, you will not be able to debug source code put into
include files.  You can easily debug code in separately compiled source files.
Use this technique, rather than that of include files, if you want to debug a
large program.

Pascal permits you to put more than one statement on a line, yet it is
difficult to debug programs with multiple statements on a single line. For
example, the following code is perfectly legal in Pascal:

	if i = max then begin k := k+1; i := 0 end;

This code is actually made up of five separate source statements.  When placed
on the same line, the individual statements cannot be accessed during
debugging.  You could not, for example, stop program execution at k := k+1;
The same code would be easier to debug if it were written as:

	if i = max then
		 begin
			k := k+1;
			i := 0
		 end;
Writing only one statement on a line makes code easier to read and corresponds
with what is generally considered good programming practice.

Compiling and Linking Pascal Programs

Versions 4.0 and later of Microsoft Pascal support the CodeView options /Zi
and /Zd, when you use the PL driver program.  (For a descripton of these
options, see Section 1.2.2, "CodeView Compile Options.")  The CodeView compile
options are put on the command line when invoking the first pass of the Pascal
compiler.

The /CO option is necessary only when you link separately.

<*>  Example

PL /Zi /c TEST
LINK /CO TEST;

The example above compiles the source file TEST.PAS to produce an object file,
TEST.OBJ, which contains the symbol and line-number information required by
the CodeView debugger.  Then the linker is invoked with the /CO option.  The
CodeView debugger supports mixed-language programming.  For an example of how
to link a Pascal module with modules from other languages, see Section 1.2.8
below, "Preparing Assembly Programs."

1.2.8  Preparing Assembly Programs

In order to use all the features of the CodeView debugger with assembly
programs, you will need to assemble with Microsoft Macro Assembler, Version
5.0 or later.  (Section 1.6 discusses how to use earlier versions of Microsoft
Macro Assembler with the debugger.)  No matter what version of the assembler
you use, you will need to link with the Microsoft Overlay Linker, Version 3.6
or later.

Writing Assembler Source Code

If you have Version 5.0 of the Microsoft Macro Assembler, then you can use the
simplified segment directives described in the Microsoft Macro Assembler
Programmer's Guide.  Use of these directives ensures that segments will be
declared in the correct way for use with the CodeView debugger. (These
directives also aid mixed-language programming.) If you do not use these
directives, then you need to make sure that the class name for the code
segment is CODE.

---------
Important
---------
The CodeView debugger correctly recognizes floating-point values only when
they are in the IEEE (Institute of Electrical and Electronics Engineers,
Inc.) format.  You should use the IEEE format with any program that you are
going to run with the CodeView debugger if that program uses floating-point
variables.  The IEEE format is the default for Version 5.0 of the Microsoft
Macro Assembler.  You can always specify IEEE format by using the .8087 or	 
.287 directive, or by assembling with the /R option.
====

You will not be able to trace through macros while in source mode.  Macros
will be treated as single instructions unless you are in assembly or mixed
mode, so you will not see comments or directives within macros.  Therefore,
you may want to debug code before putting it into a macro.

The Microsoft Macro Assembler also supports include files, but you will not be
able to debug code in an include file.  You are better off reserving include
files for macro and structure definitions.  Because the assembler does not
have its own expression evaluator, you will have to use either the C-,
FORTRAN-, BASIC-,  Pascal-expression evaluator.  C is the default because it
is the closest to assembly language.  To make sure that the expression
evaluator recognizes your symbols and labels, you should observe the following
guidelines when you write assembly modules:

* The assembler has no explicit way to declare real numbers.  However,
it will pass the correct symbolic information for reals and integers
if you initialize each real number with a decimal point and each inte-
ger without a decimal point. (The default type is integer.) For
example, the following statements correctly initialize REALSUM as a
real number and COUNTER as an integer:

REALSUM		DD		0.0
COUNTER		DD		0

You must initialize real number data in data definitions.  If you use
?, then the assembler will consider the variable an integer when it	 
generates symbolic information.  The CodeView debugger, in turn, will
not properly evaluate the value of the variable.

* Avoid the use of special characters in symbol names. The C-, FORTRAN-,
BASIC-, and Pascal-expression evaluators each apply their own stand-
ards in determining what is a legal symbol name.  Generally, only
alphanumeric characters and the underscore (_) are recognized.  BASIC
accepts certain type-declaration characters at the end of a name, but
C, FORTRAN, and Pascal do not.

* Assemble with /MX or /ML to avoid conflicts due to case when you do
mixed-language programming.  By default, the assembler converts all
symbols to uppercase when it generates object code.  C, however, does
not do this conversion.  Therefore, the CodeView debugger will not
recognize that var in a C program and var in an assembly program are
the same variable unless you leave Case Sense off when using the
debugger.

* If you access command-line data in the Program Segment Prefix (PSP),
note that the CodeView debugger changes the PSP; tabs, quote marks, and
extra spaces are removed so that exactly one space separates each argu-
ment.  The debugger retains quote marks (along with any quoted mater-
ial) for command lines given with the L command.

Assembling and Linking

The assembler supports the /Zi and /Zd assemble-time options.  The /Od option
does not apply and so is not supported.  Assembler options are not case
sensitive.  You may therefore enter /ZI or /ZD on the assembler command line to
produce an object file in the CodeView format.

If you  link your assembly program with a module written in C (which is case
sensitive), you probably need to assemble with /MX or /ML.

After assembling, link with the /CO option to produce an executable file in
the CodeView format.

<*>  Examples

MASM /ZI EXAMPLE;
LINK /CO EXAMPLE;

MASM /ZI MOD1;
MASM /ZD MOD2;
LINK /CO MOD1 MOD2;

CL /Zi /Od /c /AL prog.c
BC /Zi sub1;
MASM /ZI /MX sub2;
LINK /CO prog sub1 sub2

The first example assembles the source file EXAMPLE.ASM and produces the
object file EXAMPLE.OBJ, which is in the CodeView format.  The linker is then
invoked with the /CO option and produces an executable file with the symbol
table and line-number information required by the debugger.

The second example produces the object file MOD1.OBJ, which contains symbol
and line-number information but no symbol table.  The object files are then
linked.  The result is an executable file in which the second module will be
harder to debug.  This executable file, however, will be smaller than it would
be if both modules were assembled with the /ZI option.

The last example demonstrates how to create a mixed-language executable file
that can be used with the CodeView debugger.  The debugger will be able to
trace through different source files in the same session, regardless of the
language.


.end of ch.1a.